[auto] sync agent CLI harnesses with upstream docs#489
Conversation
Audit of all seven integrated agent CLIs (Claude, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) against their current upstream hook docs. Five are up to date; two show scope-2 tool-map drift that needs a human decision, so they are surfaced in the PR reviewer checklist rather than auto-edited: - Gemini: save_memory no longer in the upstream tools reference; GEMINI_TOOL_MAP entry is now stale. - Pi: PI_TOOL_MAP maps `glob`, absent from the audited upstream tool set (find/ls documented instead) — and the audited package is deprecated in favor of @earendil-works/pi-coding-agent, so confirm the real target first. No hook-event-name (scope 1) or settings-file-shape (scope 3) drift found. Pi's larger upstream event surface is intentional curation, not drift. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds the ChangesAudit documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🔍 Automated code review started — analyzing [{"additions":5,"deletions":0,"path":"CHANGELOG.md"}] files, +5/-0... ⏱️ This may take a few minutes. Results will be posted here when complete. |
|
|
||
| ## 0.0.13-beta.3 — 2026-07-12 | ||
|
|
||
| ### Fixes |
There was a problem hiding this comment.
🔵 Suggestion (non-blocking) — ### Fixes should be ### Docs
This entry sits under ### Fixes, but the PR changes only CHANGELOG.md and — as the PR description states — "makes no code changes." The two *_TOOL_MAP drifts (Gemini save_memory, Pi glob) were deliberately not fixed; they were deferred to the reviewer checklist. So nothing was actually fixed in 0.0.13-beta.3.
Per this repo's CLAUDE.md changelog guidance:
- Fixes for bug fixes
- Docs for documentation-only changes
A documentation/audit entry with no code change belongs under ### Docs.
Suggested fix: rename this heading from ### Fixes to ### Docs.
Not blocking — CI is unaffected, and the version/date/heading are all consistent (0.0.13-beta.3 — 2026-07-12). This is release-hygiene only.
🔍 Automated Code Review📋 Executive SummaryThis is a documentation-only PR: a single 📊 Change Architecturegraph TD
A[7 CLI hook harnesses<br/>types.ts: *_TOOL_MAP + *_HOOK_EVENT_TYPES] -->|audited vs upstream docs| B{Drift?}
B -->|Claude · Codex · Copilot<br/>Cursor · OpenCode| C[Up to date — no change]
B -->|Gemini save_memory<br/>Pi glob| D[Tool-map drift flagged]
D -->|human decision — deferred| E[Reviewer checklist<br/>in PR body]
D -->|documented, not auto-edited| F[New: CHANGELOG.md entry<br/>0.0.13-beta.3]
style F fill:#90EE90
style D fill:#FFD700
style A fill:#87CEEB
Legend: 🟢 New (CHANGELOG entry) · 🔵 Modified · 🟡 Drift flagged & deferred 🔴 Breaking Changes✅ None. No code, schema, API, config, dependency, or serialization changes — the diff is one Markdown paragraph.
|
| Claim in entry | Verified against | Result |
|---|---|---|
GEMINI_TOOL_MAP maps save_memory |
src/hooks/types.ts:620 (save_memory: "Memory") |
✅ present |
PI_TOOL_MAP maps glob; find/ls unmapped |
src/hooks/types.ts:478‑485 |
✅ correct |
| Pi subscribes to a curated 7-event set | PI_HOOK_EVENT_TYPES (7 entries) |
✅ exact |
| Reviewer-checklist test refs | integrations.test.ts:1296, handler.test.ts:683, handler.test.ts:977 |
✅ all resolve |
| Version/date consistency | package.json = 0.0.13-beta.3; today = 2026-07-12 |
✅ match |
On the deferral decision: deferring both drifts rather than auto-editing is sound. Removing save_memory → Memory / glob → Glob would be a no-op if the tools are gone but a canonicalization regression if they still exist, and the PR correctly notes the audited Pi package (@mariozechner/pi-coding-agent) is deprecated in favor of @earendil-works/pi-coding-agent — so acting on unverified drift would be risky. Leaving the mappings in place is the safe call.
🧪 Evidence — Build & Test Results
No Docker/web-UI to exercise (markdown-only diff). I ran the one CI check semantically tied to a version+changelog PR and confirmed the rest are unaffected.
version-consistency check (from .github/workflows/ci.yml quality job)
version-consistency check: PASS (root=0.0.13-beta.3, packages/ dirs found=0)
CHANGELOG top heading: ## 0.0.13-beta.3 — 2026-07-12
package.json version : 0.0.13-beta.3
The check loops over packages/*/package.json (none exist) and packages/wrapper/package.json (absent, guarded by || true), so it passes trivially — and the top heading matches the root version.
Diff scope & branch state
Changed files (PR vs main):
CHANGELOG.md (+5 / -0)
Commits on branch not on main:
202759f feat: sync agent CLI harnesses with upstream docs
Main commits missing from branch: (none — branch is up to date with main)
lint / tsc / test / build
Unaffected — the diff touches only CHANGELOG.md (Markdown). eslint lints code (not the changelog),
tsc sees no TS change, vitest sees no source/test change, and the build has no new inputs. There is
also no CI changelog-format validator (grep of .github/ + scripts/ found none).
Note: the untracked, 0-byte
claude-output.txtin the working tree is a review-session artifact, not part of this PR, and was left untouched.
🔗 Issue Linkage
hook-sync container). The PR body's per-CLI table and reviewer checklist provide adequate traceability. The two flagged drifts are good candidates for follow-up tracking issues once the real Pi target (@earendil-works/pi-coding-agent) is confirmed.
💡 Suggestions
- Relabel
### Fixes→### Docs(inline). The only actionable item. - Consider opening a tracking issue for each deferred drift so the checklist survives the PR merge.
- Optional: a
feat:→docs:/chore:commit prefix would match the no-code reality, if the repo doesn't squash-rewrite.
🏆 Verdict
Fixes → Docs). Not merge-blocking.
Automated code review · 2026-07-12
hermes-exosphere
left a comment
hermes-exosphere
left a comment
There was a problem hiding this comment.
Automated review complete. ✅ Approved with one non-blocking suggestion.
Documentation-only PR (only CHANGELOG.md, +5/-0). Every factual claim in the entry was verified against the source (GEMINI_TOOL_MAP.save_memory, PI_TOOL_MAP.glob, the 7-event PI_HOOK_EVENT_TYPES, and all three reviewer-checklist test line refs) — all accurate. Version/date/heading are consistent (0.0.13-beta.3 — 2026-07-12) and the CI version-consistency check passes. The deferral of both tool-map drifts is the correct, safe call.
Sole nit (see inline): the entry is under ### Fixes but nothing was fixed — per CLAUDE.md it should be ### Docs. Not merge-blocking.
2 participants
Automated
ultracodesync run: one subagent per integrated agent CLI fetched the CLI's current upstream hook docs and diffed them against this repo's*HOOK_EVENT_TYPESarrays,*_TOOL_MAP/*_TOOL_INPUT_MAPtables, per-CLIpolicy-evaluator.tsbranches,integrations.tswriter literals, and committed dogfood fixtures. Every claimed drift was re-checked by a second, skeptical verifier agent before being reported.Outcome: five CLIs are up to date; two show tool-map (scope-2) drift. Both drift items are judgement-heavy (which canonical name a removed/renamed tool maps to is a human decision, and one relies on a deprecated upstream package), so per the run contract they are surfaced below as reviewer-checklist items rather than auto-edited. There are no hook-event-name (scope-1) appends and no settings-file-shape (scope-3) fixes, so this PR makes no code changes — only the reviewer checklist and a
CHANGELOG.mdentry.Summary
Per-CLI drift
Pi (
@mariozechner/pi-coding-agent)badlogic/pi-monoextensions.md) documents 33pi.on(...)events; the repo'sPI_HOOK_EVENT_TYPESintentionally subscribes to a curated 7-event parity set (session_start,session_shutdown,input,tool_call,user_bash,tool_result,agent_end), the same design as Cursor. The 26 extra events (turn_start,turn_end,agent_settled,model_select,thinking_level_select,before_provider_request,context,session_before_fork, …) are Pi-specific with no canonical Claude lifecycle equivalent and are deliberately unsubscribed — not drift. No append.PI_TOOL_MAPmapsglob → Glob, but the audited upstream lists core tools asread, bash, edit, write, grep, find, ls— there is noglob(Pi documentsfindfor name/pattern matching), andfind/lsare unmapped.read/write/edit/bash/grepall still match..pi/settings.jsonpackages-array shape is not described by the accessible docs; no change detected.Gemini CLI
https://geminicli.com/docs/hooks/still enumerates exactly the 11GEMINI_HOOK_EVENT_TYPES(confirmed verbatim by the verifier).save_memoryis no longer present in the upstream tools reference (https://geminicli.com/docs/reference/tools/); the Memory category now listsactivate_skillandget_internal_docs.GEMINI_TOOL_MAPstill mapssave_memory → Memory, so that entry is now stale. Every other mapped tool id was confirmed present and unchanged (notablyrun_shell_commandwas not renamed toshell, andgrep_searchwas not renamed togrep)..gemini/settings.jsonshape confirmed: per-eventmatcherfield present,timeoutin milliseconds (default 60000) — matches the writer'stimeout: 60_000.Reviewer checklist
GEMINI_TOOL_MAP—save_memoryis no longer listed in the upstream tools reference (Memory category now showsactivate_skill/get_internal_docs). Decide whether to drop the stalesave_memory: "Memory"entry fromsrc/hooks/types.tsand whether to map the new tools. Note:save_memoryis also pinned in__tests__/hooks/integrations.test.ts:1296and__tests__/hooks/handler.test.ts:683, so a removal must update those. Not auto-applied because a two-agent read of a reorganized docs page could miss a moved entry, and dropping a live mapping would regress canonicalization ifsave_memorystill exists.PI_TOOL_MAP—glob → Globmaps a tool absent from the audited upstream set (find/lsare documented instead and unmapped). Decide the canonical mapping (find → GlobvsGrep;ls → LS) and whether to dropglob. Not auto-applied because: (a) the canonical mapping is a human decision, (b) any change must be mirrored intopi-extension/index.ts(the in-process shim, outside this run's allowed edit scope) and__tests__/hooks/handler.test.ts:977, and (c) source ambiguity — see Unverified notes.Sources
Unverified notes
unverified(every CLI yielded a parseable enumeration), but two source caveats affect confidence:npmjs.com/@mariozechner/pi-coding-agent) returned HTTP 403; the audit fell back to the authoritative event/tool enumeration in the repo linked from the npmrepositoryfield (badlogic/pi-monoextensions.md). Importantly, that npm package is deprecated in favor of@earendil-works/pi-coding-agent, which this repo's own code comments cite as the integration target. Theglobvsfind/lsdiscrepancy may therefore reflect a fork difference rather than drift in the repo's actual target — confirm against@earendil-works/pi-coding-agentbefore acting.developers.openai.com/codex/hooks) now 308-redirects tolearn.chatgpt.com/docs/hooks. The current docs present event names in PascalCase; the repo's snake_caseCODEX_HOOK_EVENT_TYPESis an internal canonicalization enum and its writer already emits the matching PascalCase keys, so this is not drift.CI is expected to fail on this PR if a map-bearing CLI gained new events — a reviewer must add the missing
*EVENT_MAPentries (replacing"???") before merging. For drift in Claude or Copilot only (no event map), CI should pass on this commit alone. CI must pass and this PR must be reviewed before merging.(No map-bearing CLI gained new events in this run, so CI is expected to pass on this commit — the two drift items are checklist-only.)
🤖 Generated with Claude Code
Summary by CodeRabbit